Description

Part of epic #493 (Phase 2 — payout money-accuracy). Branches directly off master, since #503/#504/#505 are all merged.

markPayoutPaid was a one-way ratchet: once a payout was recorded, nothing re-checked whether the underlying transactions it was based on later flipped to refunded. Since getPayoutsOwed() only ever queried status = 'successful', a refunded transaction simply vanished from the calculation with no trace — netOwed would silently drop to $0.00 for that tenant going forward, absorbing the loss with no record that a refund had happened.

Changes made

• lib/payments/payouts-owed.ts — PlatformSettledTxn gained a status: 'successful' | 'refunded' field. computeOwedBalances now includes refunded transactions in the aggregation instead of relying on the caller to filter them out: a refunded transaction no longer contributes to grossCollected/grossOwed/byProvider, but its scaled amount (same split-percentage logic as any sale — snapshot-or-current) is added to a new clawback figure. netOwed is now max(grossOwed - alreadyPaid - clawback, 0).
• CurrencyBalance gained a clawback: number field — always present and visible, even when 0.
• app/actions/platform/payouts.ts — getPayoutsOwed() now selects status and queries .in('status', ['successful', 'refunded']) instead of .eq('status', 'successful'), and passes status through to computeOwedBalances.
• app/[locale]/platform/payouts/page.tsx — adds a "Clawback" column to the by-school table (shown as −$X.XX in red when non-zero, — otherwise) and a red banner above the table summarizing total clawback per currency whenever any tenant has one, so a refund-after-payout is visible rather than silently netted away.

Type of change

• Bug fix (money-accuracy — a refund on an already-paid-out sale previously vanished with no trace instead of reducing what's owed next cycle)

Closes #498 (Phase 2 sub-task of epic #493).

Testing

• npx vitest run tests/unit/payouts-owed.test.ts — 18/18 passing, including 4 new tests specific to No refund/chargeback clawback for manual payouts already marked paid #498 (refund-after-payout produces a visible clawback and reduces netOwed; clawback is reported even with nothing else outstanding; a refund in one currency doesn't clawback a balance in another currency; clawback uses the transaction's own snapshotted split, not the tenant's current one).
• npm run test:unit — 277/277 passing, no regressions.
• npm run typecheck — clean.
• npm run lint on changed files — no new errors (one pre-existing unused-var warning in payouts.ts predates this change, unrelated to it).
• npm run build — succeeds.
• Live-verified locally: seeded a $100 USD PayPal sale with status = 'refunded' (80% split snapshot) for a tenant that already had an $80 manual payout recorded against it, then loaded /platform/payouts as a super admin. Screenshot attached below shows: Collected $0.00 (the refunded sale no longer counts as collected), Paid so far $80.00, Clawback −$80.00 in red, Owed $0.00, and the red clawback banner summarizing it above the table. Test data cleaned up afterward.

QA verification steps

1. In a local Supabase shell, create a successful PayPal transaction for a tenant, record a manual payout against it via the "Mark as Paid" dialog on /platform/payouts.
2. Flip that transaction's status to refunded directly in the DB (simulating a later refund).
3. Reload /platform/payouts — confirm a red "Refund clawback" banner appears, the tenant's row shows a −$X.XX clawback figure, and "Owed" reflects the reduction (floored at $0.00, never negative).
4. Confirm the refunded transaction's amount is excluded from the "Collected" column (it never happened, from a bookkeeping standpoint) while still being visible via the clawback figure.

Screenshot

Attached as a PR comment: the payouts page showing the clawback banner and table row for the refund-after-payout scenario.